package dao;

import java.io.Serializable;

/**
 * GenericDao interface. DAO pattern interface whose implementations can be
 * specific for different types. Covers the basic CRUD operations.
 *
 * @author quirozca
 *
 * @param <T>
 *            Target class to be persisted
 * @param <PK>
 *            Class of the primary key
 */
public interface GenericDao<T, PK extends Serializable> {
	/**
	 * Gets a reference to an object from the database using the given primary
	 * key
	 *
	 * Note that this is a reference only and it may happen that the reference
	 * is stale for example if the item has been deleted elsewehere
	 *
	 * @param id
	 *            Key to find the object
	 * @return Returns the object reference
	 */
	T readReference(PK id);

	/**
	 * Persists a new instance object into the database
	 *
	 * @param newInstance
	 *            The new object to be persisted
	 * @return The primary key of the object
	 */
	PK create(T newInstance);

	/**
	 * Deletes an existing object from the database
	 *
	 * @param persistentObject
	 */
	void delete(T persistentObject);

	/**
	 * Reads an object from the database using the given primary key Returns
	 * null if not found
	 *
	 * @param id
	 *            Key to find the object
	 * @return Returns the object or null if not found
	 */
	T read(PK id);

	/**
	 * Updates an existing object based on the primary key
	 *
	 * @param transientObject
	 */
	void update(T transientObject);
}
